Acorn User: China

home *** CD-ROM | disk | FTP | other *** search

/ Acorn User: China / Acorn User China CD-ROM (UK) (Disc B) / Acorn User China CD-ROM (UK) (Disc B).bin / STUTTGART / DATABASE / ULTIMATE / a252buf.txt < prev next >

Wrap

Text File | 1993-08-09 | 12.8 KB | 425 lines

Buffer Manager ============== The buffer manager provides a global buffer managing system, it provides a set of calls for setting up a buffer, inserting and removing data from a buffer and finally removing a buffer. It is also possible to setup an area of memory to be used as a buffer. The buffer manager extends the INSV, REMV and CNPV to provide access to these buffers and also allow block transfers. The buffer manager is used by DeviceFS to provide buffers for the various devices that can be accessed. A device may be linked to a buffer supply routines to be called when data enters the buffer and also a routine to be called when a buffer is removed (or a new device is attached). When registering or creating a buffer it is possible to force a specific buffer handle, if this feature is not used then the manager will asign a unique handle to it. It should be noted that buffer handles are no longer stored as eight bit quanities. Block transfers are signalled by setting bit 31 of the buffer handle, anything which can be performed on a byte by byte basis can also be performed on a block, eg. examine the buffer contents. SWI interface ============= Buffer_Create ------------- in: r0 = flags for the buffer bit 0 =0 => buffer is dormant and should be woken up when data enters it bit 1 =1 => buffer generates "output buffer empty" events bit 2 =1 => buffer generates "input buffer full" events bit 3 =1 => buffer generates upcalls when free space threshold crossed (from above or below) bits 4-31 reserved for future expansion, should be set to zero on creation r1 = size of buffer to be created r2 = buffer handle to assign to buffer, -1 for does not matter out: V =0 => r0 = buffer handle V =1 => r0 -> error block This routine claims an area of memory from the RMA and links it into the buffer list, if r2 =-1 then the buffer manager will attempt to find a unique handle, if r2 <>-1 then the buffer manager will check that the handle specified is unique and then if it is assign it to that buffer. The flags word is used to indicate what should happen when data is being inserted and removed from the buffer. Bit 0 is used to indicate if the device attached to the buffer has been woken up, when =0 then the device is dormant and needs to be woken. When a device is attached and data is put into the buffer this bit is checked, if it is =0 then the wake up code for the device will be called allowing any device to wake up any hardware it may be driving and to start processing data within the buffer. Bit 1 is used to indicate if "output buffer empty" events should be issued for this buffer. Bit 2 is used to indicate if "input buffer full" events should be issued for this buffer. Bit 3 is used to indicate if buffer threshold UpCalls should be issued for this buffer. On exit r0 contains the buffer handle being used or a pointer to an error block. Buffer_Remove ------------- in: r0 = handle of buffer to be removed out: V =1 => r0 -> error block, else preserved This call should only be made on buffers created using Buffer_Create. It attempts to de-register the buffer from the active list and assuming that worked ok it will attempt to free the memory relating to that buffer. Buffer_Register --------------- in: r0 = flags for buffer (see above) r1 -> start of memory for buffer r2 -> end of buffer (+1) r3 = handle to be assigned to buffer (-1 if to be generated) out: V =0 => r0 = handle for buffer V =1 => r0 -> error block This call registers an area of memory as a buffer, the routine accepts similar parameters to the Buffer_Create SWI, but instead of the call claiming tha area of memory for you, you must actually specify the buffer's start and end addresses. It is not advisable to put buffers in application workspace, this area of memory can be switched out when someone else tries to access it. It is however possible for your task if it is going to be the only one using this buffer, and it will only be accessed whilst the task is currently paged in to register a buffer within its workspace. For further details about the flags word and the specified buffer handle see the Buffer_Create call. Buffer_Deregister ----------------- in: r0 = handle of buffer to be deregistered. out: V =0 => all preserved. V =1 => r0 -> error block. This call will simply unlink a buffer from the active list, the data within the buffer will be purged and any access to this buffer via INSV, REMV and CNPV will be ignored. Do not use this call if you have created the buffer using Buffer_Create, instead use Buffer_Remove which releases any memory that may have been claimed. Buffer_ModifyFlags ------------------ in: r0 = handle of buffer to be modified r1 = EOR mask r2 = AND mask out: r1 = old value r2 = new value This call allows you to modify the flags word stored with each buffer, the SWI allows two registers to be ANDed and then EORed with the current flags word, on exit the old and new values of this word are returned to the caller. r1, r2 are applied as follows: new = (old AND r2) EOR r1 The caller should not modify reserved flag bits when issuing this call, ie bits 4 to 31 should be set in r2 and clear in r1. Buffer_LinkDevice ----------------- in: r0 = buffer handle, r1 -> code to wake up device when needed (0 => none) r2 -> code to call when device to be detached (0 => cannot be detached) r3 = private word to be passed in r4 -> workspace for above routines out: V =1 => r0 -> error block, else all preserved. This call links a set of routines to the specified device, the caller supplies two routines, one to be called when data enters the buffer and another to be called when someone else attempts to link to the buffer. r1 this contains a pointer to the routine to be called when data enters the buffer and it is currently marked dormant, the routine can be entered in any mode and with FIQs or IRQs enabled / disabled, the mode should be preserved as should the interrupt state. The registers to the wake up code are setup as follows: in: r0 = buffer handle r8 = private word (specified in r3 in SWI Buffer_LinkDevice) r12 -> workspace for routine (specified in r4 in SWI Buffer_LinkDevice) out: all should be preserved, including PSR. The buffer manager automatically marks the buffer as active (non-dormant) before calling the wake up code. If the caller to Buffer_LinkDevice specifies a routine pointer equal to zero then no wake up call is made. The second routine supplied is a routine to be called whenever the owner of the buffer is about to change; if this value is zero then the device is indicating that the owner can never be changed and changing it will result in an error. The routine if supplied gets called as follows: in: r0 = buffer handle r8 = private word r12 -> workspace for the calls out: V =1 => r0 -> error block V =0 => all preserved On return from this routine the routine can return an error, any errors returned halt the detach process. The detach routines are called when someone attempts to kill the buffer manager module, this results in an error and the buffer manager refuses to die. When attaching to a buffer it is possible that the SWI will fail, this is likely to be because the current owner is refusing to detach itself. Buffer_UnlinkDevice ------------------- in: r0 = buffer handle out: V =0 => all preserved and device detached. V =1 => r0 -> error block. This routine will unlink a device from a buffer, no warning if given of the detach and the data that is currently stored within the buffer is purged. This call should only be used by the actual device that called Buffer_LinkDevice, anyone else calling this SWI could confuse the system. Buffer_GetInfo -------------- in: r0 = buffer handle out: V =1 => r0 -> error block V =0 => r0 = flags relating to buffer r1 -> start of buffer in memory r2 -> end of buffer in memory (+1) r3 = insert index for buffer r4 = remove index for buffer r5 = remaining free space in buffer r6 = number of characters in buffer This call returns data about the buffer, its position in memory, flags, insert and remove offsets and the amount of free space. Buffer_Threshold ---------------- in: r0 = buffer handle r1 = threshold / 0 none / -1 to read out: r1 = previous value This call is used to set/read the warning threshold of the buffer. This is used to trigger UpCalls if bit 3 of the buffer flags is set. The UpCalls are issued when the amount of free space in the buffer crosses the threshold value (see the UpCalls section below) Vector calls ============ The SWIs for the buffer manager module allow you to modify and tinker with the actual buffer itself, they do not however supply a way of inserting and removing data from these buffers. Extensions have been made to the three vectors; InsV, RemV and CnpV to handle the inserting and removing of data from the buffers, these calls have also been extended to allow block inserts. For compatibility marking a block operation is done by setting bit 31 of the buffer handle. This changes the specification for calling these vectors as follows: InsV ---- in: r0 = byte to be inserted r1 = buffer handle (bit 31 is clear) out: r0, r1 preserved r2 corrupt or:- in: r1 = buffer handle (bit 31 is set) r2 -> first byte of data to be inserted r3 = number of bytes to insert out: r0, r1 preserved r2 -> remaining data to be inserted r3 = number of bytes still to be inserted On both calls C is used to indicate if the insertion failed, if C=1 then it was not possible to insert all the specified data, or the specified byte. RemV ---- in: r1 = buffer handle (bit 31 clear) out: r0 = next byte to be removed (for examine only) r1 = preserved r2 = byte removed (for remove only) or:- in: r1 = buffer handle (bit 31 set) r2 -> buffer to be filled r3 = number of bytes to place into buffer out: r0, r1 preserved r2 -> updated buffer position r3 = number of bytes still to be removed On both of the above calls V =1 on entry indicates that the data should be copied out (examine) and V =0 indicates that the data should actually be removed. On exit C is used to indicate if the calls actually worked and if a byte or the requested block of data could be obtained. CnpV ---- Unchanged, except it copes with buffer manager buffers. Events ====== With the changes required to InsV, RemV and CnpV calls to cope with the new buffers and block transfers some of the events have been extended to cope with indicating that a block transfer occurred. For further details of the events and when they are generated consult the PRM, as this remains unchanged. Event_OutputEmpty ----------------- in: r0 = Event_OutputEmpty (0) r1 = buffer handle out: all preserved. This is issued when the last character is removed from a buffer which has output empty events enabled (see description of buffer flags). Event_InputFull --------------- in: r0 = Event_InputFull (1) r1 = buffer handle (bit 31 clear) r2 = character not inserted or:- r0 = Event_InputFull (1) r1 = buffer handle (bit 31 set) r2 -> data not inserted r3 = number of bytes not inserted out: all preserved. This event is generated when a character or block is inserted into a buffer which has input full events enabled (see description of buffer flags), and the insertion failed. Service calls ============= Service_BufferStarting (&6F) ---------------------------- in: r1 = Service_BufferStarting (&6F) out: all preserved. This call is passed around after the module has been initialised or reset. It allows module which wish to register buffers with the buffer manager to do so. When the service is received all SWIs are valid. UpCalls ======= UpCall_BufferFilling (8) ------------------------ in: r0 = 8 r1 = Buffer handle r2 = 0 out: - This is issued when data is inserted into the buffer and the free space becomes less than the specified threshold. UpCall_BufferEmptying (9) ------------------------- in: r0 = 9 r1 = Buffer handle r2 = -1 out: - This is issued when data is removed from the buffer and the free space becomes greater than or equal to the current threshold.